import Doc from '~/components/layout/docs'
import Link from '~/components/text/link'
import { Image } from '~/components/media'
import Caption from '~/components/text/caption'
import Snippet from '~/components/snippet'
import Note from '~/components/text/note'
import { InlineCode } from '~/components/text/code'

export const meta = {
  title: 'Deployments',
  description: 'Understanding and making deployments with ZEIT Now.',
  editUrl: 'pages/docs/v2/platform/deployments.mdx',
  lastEdited: '2020-01-24T23:33:43.000Z'
}

A deployment is the result of building your [Project](/docs/v2/platform/projects/) and making it available through a live URL.

This section contains information about making, managing, and understanding the behavior of deployments.

## Making Deployments

There are multiple ways to make deployments with ZEIT Now; these include via a [ZEIT Now for Git Integration](#git-integration), [Deploy Hooks](#deploy-hooks), [Now CLI](#now-cli), and the [ZEIT Now API](#now-api).

When making deployments, the [Project](/docs/v2/platform/projects/) will be uploaded and transformed into a production-ready output through the use of a [Build Step](/docs/v2/build-step).

Once the build step has completed successfully, a new, [immutable](https://en.wikipedia.org/wiki/Immutable_object) deployment will be made available at the [preview URL](/docs/v2/platform/deployments/#preview).

### Git Integration

You can make deployments with Git by using either the [ZEIT Now for GitHub](/docs/v2/git-integrations/zeit-now-for-github), [ZEIT Now for GitLab](/docs/v2/git-integrations/zeit-now-for-gitlab), or [ZEIT Now for Bitbucket](/docs/v2/git-integrations/zeit-now-for-bitbucket) integrations.

When using these integrations, every push to a branch will provide you with a [preview deployment](/docs/v2/platform/deployments/#preview) to view your changes.

When merging to the default branch (commonly `master`), a [production deployment](/docs/v2/platform/deployments/#production) will be made.

### Deploy Hooks

[Deploy Hooks](/docs/v2/advanced/deploy-hooks/) allow you to create URLs that accept HTTP POST requests to trigger deployments, re-running the [Build Step](/docs/v2/build-step), from outside of ZEIT.

There are many use cases for Deploy Hooks, for example, rebuilding your site to reflect changes in a Headless CMS or scheduling deployments with Cron Jobs.

To create a Deploy Hook, visit the settings page of your [Project](/docs/v2/platform/projects/) where you can choose the branch to deploy when the HTTP endpoint receives a POST request.

<Note>
  Deploy Hooks require a{' '}
  <Link href="/docs/v2/git-integration/">Git Integration</Link> to be installed.
</Note>

You can find more information about Deploy Hooks in the [documentation](/docs/v2/advanced/deploy-hooks/).

### Now CLI

By using [Now CLI](/download), you can deploy [Projects](/docs/v2/platform/projects/) with **a single command** from your terminal.

To make a [preview deployment](/docs/v2/platform/deployments/#preview), use the `now` command:

<Snippet dark text="now" />
<Caption>Making a preview deployment with the <InlineCode>now</InlineCode> command.</Caption>

<Note>
  The first deployment for a <strong>Project</strong> is always both a{' '}
  <Link href="/docs/v2/platform/deployments#preview">preview</Link> and{' '}
  <Link href="/docs/v2/platform/deployments#production">production</Link>{' '}
  deployment.
</Note>

To make a [production deployment](/docs/v2/platform/deployments/#preview), use the `now --prod` command:

<Snippet dark text="now --prod" />
<Caption>Making a production deployment with the <InlineCode>now</InlineCode> command.</Caption>

### Now API

The [ZEIT Now API](/docs/api/) can be used to make deployments by making an HTTP POST request to the relevant endpoint, including the files you wish to deploy as the body.

You can find more information about the ZEIT Now API in the [API Reference](/docs/api/#endpoints/deployments).

## Deployment Types

There are two types of deployment on the ZEIT Now platform: **preview** and **production**.

### Preview

**Preview deployments** are the default for all deployments. Each time you push to a branch or make a deployment using the `now` command, this is a **preview deployment**.

By making a **preview deployment**, the **preview URL** will be updated to reflect that of the latest deployment made.

The **preview URL** is provided on a pull or merge request when using a [ZEIT Now for Git Integration](/docs/v2/git-integrations) and contains the name of the user or team to which the [Project](/docs/v2/platform/projects) belongs.

### Production

**Production deployments** are made in two different circumstances. Each time you merge to the default branch (commonly `master`) or make a deployment using the `now --prod` command, this is a **production deployment**.

By making a **production deployment**, the **production domain(s)** will be updated to reflect that of the latest deployment.

The **production domain(s)** are defined from the **Domains** tab of a Project on the ZEIT Dashboard.

To add a **production domain** to a [Project](/docs/v2/platform/projects/), visit **Domains** from the Project Overview page, you can read more about this in the [custom domains documentation](/docs/v2/custom-domains/).

## Managing Deployments

You can manage your deployments either via the [ZEIT Dashboard](/dashboard) or, in advanced use cases, [Now CLI](/download).

### ZEIT Dashboard

The [ZEIT Dashboard](/dashboard) is the easiest way for you to manage your deployments.

Through the ZEIT Dashboard, you can find a variety of settings; including a **Domains** tab where you can add [custom domains](/docs/v2/custom-domains/) to your Project.

### Now CLI and API

The [Now CLI](/download) and [Now API](/docs/api/) provide alternative ways to manage your deployments.

You can find a full list of the commands available in the [Now CLI Reference](/docs/now-cli/), along with the deployments section of the [Now API Reference](/docs/api/#endpoints/deployments).

## Logs

There are three types of logs available, **Build Time**, **Runtime**, and **Edge Network**.

### Build Time

**Build Time** logs are generated during the [build step](/docs/v2/build-step/). These logs contain information about the build process and are stored **indefinitely**.

### Edge Network

**Edge Network** logs are generated when requesting a path from the Edge. These logs contain information about a request to a specific path with details such as the path name, request method, and status code. These logs are **not persisted**.

### Runtime

**Runtime** logs are generated by [Serverless Functions](/docs/v2/serverless-functions/introduction) while they're being invoked. Runtime logs are stored in memory only as they arrive from the Serverless Function and are **not persisted**.

The only exception to this are **failed requests**. If a request leads to the Serverless Function throwing an error, the log for this will be stored indefinitely whereas all other Runtime logs will be lost when navigating away from the page.

<Note type="hint">
  If you wish to persist <strong>Runtime</strong> or{' '}
  <strong>Edge Network</strong> logs, you can use a{' '}
  <Link href="/integrations?category=Logging">logging integration</Link>{' '}
  available from the ZEIT Integrations marketplace. Alternatively, you may build
  your own service by making use of the{' '}
  <Link href="/docs/api#endpoints/log-drains">Log Drains API</Link>.
</Note>

There is a maximum size limit of **4kb** for each log. If the size of the log exceeds this, only the last **4kb** of data to arrive will be shown.

## Special Paths

All deployment URLs have two special pathnames:

- `/_src`
- `/_logs`

### Source View

By appending `/_src` to a deployment URL or [custom domain](/docs/v2/custom-domains), the deployment inspector will be open and you'll be able to browse your deployment sources and [build](/docs/v2/build-step) outputs.

### Logs View

By appending `/_logs` to a deployment URL or [custom domain](/docs/v2/custom-domains), you will be able to see a realtime stream of logs from your deployment build processes and serverless invocations.

### Security Considerations

These pathnames redirect to `https://zeit.co` and **require logging in** to access any sensitive information. A 3rd-party can **never** access your source or logs by crafting a deployment URL with one of these paths.

## Technical Details

### Deduplication

The URL structure of each preview deployment contains the name of the application and a random UID.

ZEIT Now generates a new UID (and therefore a new deployment), by combining the following information into an internal digest that is looked up within the deployment database:

- The entire deployment configuration from `now.json`.
- The owner ID (either the user ID or team ID, if deploying within a team).
- The description of the filesystem. This includes symlinks, [modes](<https://en.wikipedia.org/wiki/Modes_(Unix)>), pathnames, and the [checksum](https://en.wikipedia.org/wiki/Checksum) of each file's contents.

ZEIT Now ensures that the digest is computed [deterministically](https://en.wikipedia.org/wiki/Deterministic_algorithm) by sorting and ordering all the inputs involved in the algorithm.

Our lookup excludes deployments that are in an `ERROR` state – if a previous deployment matches the digest but failed to build correctly.

#### Skipping Deduplication

There are two ways to force a **new** deployment to be created when our system would otherwise deduplicate.

- **Make any change** to any of the parameters considered by the algorithm, listed above. For example, even changing one character in a comment of a source file yields a new deployment.
- **Force a new deployment** by instructing your client to do so.
  - For [Now CLI](/download) you can run `now --force`
  - If using our API, include the [`forceNew` query parameter](/docs/api/v2#endpoints/deployments/create-a-new-deployment)

export default ({ children }) => <Doc meta={meta}>{children}</Doc>

export const config = {
  amp: 'hybrid'
}
